This section gives more detail than the Quick Start section above. It describes each of a trial's "fields" and their options.
After reading this, you can remind yourself of the order and/or meaning of the fields when using the script editor in two ways:
1. Inserting a header line: by placing the vertical blinking text placement cursor above where your trials will go (or are already), and then selecting the "Insert Header Line" (or Command-L) menu item under the "Control" menu. This just shows the order of the fields; or
2. Displaying the floating help palette: by clicking on the "?" pop-up button beside the "Run" button at top of the control window. This gives a brief description of each field. It can be torn off and left in the background whilst you enter your trial data. When this is visible, the header line can be inserted by dragging over to the "Insert Header" button and releasing the mouse when it hilites or clicking it like a button.
Fields
There are 11 mandatory fields in each trial, and 2 extra optional fields, all separated by tab characters:
1. The trial type ("type"):
(i) SINGLE: "S" or "s" indicates the trial is complete in itself, ie it is not attached to any other following or prior trial. It will execute, then move onto the next trial.
(ii) BLOCK: "B" or "b' indicates a member of a grouped set of trials or "block". All subsequent trials belonging to the same block must have a "B" or "b" for their trial type too, so MacStim can associate them all correctly. To terminate a block, make the next trial type any other type of trial. Animation is the usual reason for blocked trials. The time periods of each trial (ie pre, max and tot seconds) are still used in the same manner, as is the repetition time (ie rep), with one exception. The block leader's rep time determines the maximum time to play the whole block. For example, if you want to run an animation repeatedly for 20 seconds, you would ensure the first rep time was 20.0, and all other rep times can be 0.0 (or any time less than the total of their own trial's pre and max times). This is of particular importance when you use the debugging Run Selected Lines (or Command-1) menu item when you want to test just a few lines. The rep time in the top selected line should be > 0 seconds, or else the block will rapidly cycle probably without any stimuli being shown. In the same way, if you set the block header rep time to 0.0 then the block will either not display (or some transient rapid flashing may occur!). It is safer to comment out a whole block instead if you don't want it to display.
(iii) RANDOM: "R" or "r" indicate a group of trials to be randomized at run time. Only random blocks can have subtrial members, ie trials to be inseparably linked despite randomization overall. This is best illustrated by a general example. If you wish to show a background then a stimulus picture as a primer for a subsequent background and stimulus picture, and you want them to remain together despite having several combinations of these and the need to randomize these associated trial groups each time, then you would use the random block trial type, and would put 2 in the num field (for the 2 lines to be kept together). These 2 (or more) lines would then stay together inseparably despite the randomization process of the grouped trials. This is elaborated in the examples section, and makes the random block very powerful and flexible. MacStim will assume all contiguous random designated trials are part of the same random block. To separate more than one random block, you must insert a trial of another type (eg. a single trial). This can be a dummy trial with 0.00 seconds for all its parameters, which will cause the experiment to run instantaneously onto the next block. Special note: Like the block trial type, if you set the block header rep time to 0.0 then the block will either not display (or some transient rapid flashing may occur!). It is safer to comment out a whole random block instead. The same applies to running a few selected lines during debugging too.
The "Preferences" dialog will allow you to either accept MacStim's runtime randomization order for each of these blocks, or to create a new script instead, which can be inspected, edited or saved before running it. This is how you might create a master script, and daughter scripts with different random or pseudo-random stimulus orders.
(iv) PAUSE: "P" or "p" trials indicate MacStim should pause until the specified event (mouse or key press as specified in the trial stpEvt field, or externally via serial or trigger events) occurs before moving on to the next part of the trial. Be sure you fully understand how MacStim knows to move onto the next trial (eg test it with mousedown & keydown events for different trials) since MacStim looks for the specified stpEvt at the start of the pre, max and end of the max periods (hence it looks for the event type before starting the next trial, unless that trial is the very first one of the whole script). These are most useful for example trials (explanation, demonstration) or when precise experimenter control is required at initiation of blocks. Note that these will always show all 3 phases of the trial and ignore the timing field values. Hence if the event were to be a click, you would need to do 3 clicks to get to the next trial.
Any combination of these trial types is possible, for almost any length script making complex combination experiments feasible.
(v) CONTINUOUS: "C" or "c" trials indicate to play the trial as if it is a single trial type but with an effectively infinite repetition time, until the stop event (specified in the stpEvt field) is detected. I envisage this would be useful to show a flickering checkerboard (or other dynamic effect) for an indeterminate time before moving on to the next trial.
2. The number of trials to keep together ("num"):
This is usually 1, for all trial types except random. For random types, this number is the total no of consecutive trials (including the first one) to be inseparably associated with the lead trial. There can be up to 50 subtrials associated with each main or lead trial. This is designed to allow randomization of blocks of trials (eg using the priming example above) whose subtrial order does not alter, but whose main random trials can be presented in a random order. For the first random trial which specifies more than one subtrial, eg n subtrials, the num field of the next (n-1) trials will be ignored. Note that the subtrials still retain their individuality, with respect to their rep field (allowing individual subtrials to play for more than just their pre plus tot seconds). Note also that the leading line of a random block will provide the rep time for that whole block. This is provided so an experiment can repeat itself ad infinitum with a different randomized order each time. Note also then that the rep time of the leading line will be effectively 0.0 seconds when this line is executed (but it can contain dummy times so could be bypassed also).
•••TIMING NOTE! Times less than 0.05 seconds (ie 50 msecs) won't be long enough to realistically display any resource type (except none!) even with preloading, causing drop out of resources.
3. The background stimulus time ("pre"):
The time in seconds to present the background resource before starting the stimulus resource. Note that there is no default background resource, and if you wish no resource (PICT or sound) to be presented then you should mark the resource for this trial's background as "n" or "none" (see "bg" below). I do not suggest you design your experiments to include pre with a value of zero, although this will work. This period is designed to give a "rest" or preliminary period prior to presenting the expected stimulus. A negative value means MacStim should choose a random time at run time between 0.0 and the absolute value of your specified pre seconds.
4. The stimulus duration maximum ("max"):
This is also in seconds, and is a complex field. This represents the maximum time to show the stimulus resource, if no stop event is encountered. If the specified stop event does occur, then MacStim halts the stimulus resource, moves onto the background resource for any remaining time in that trial (ie pre + max or tot if tot > pre + max). A reaction time will be measured from the onset of the stimulus ie whenever it actually starts on screen or through the speaker etc, to the specified stop event. All events will be flushed before this period (and a minimum time if requested in the preferences) commences, so that the next time the specified event (see stpEvt below) is encountered the timer will stop. Note that user events will also be looked for and recorded up until the start of the next trial (ie the end of tot seconds). Thus the recording window for seeking a valid user event will extend beyond max seconds, but not into the next trial.
Using the Preferences options (under the File menu), you can alter the impact of the stop event, for example recording every time a valid event is encountered (by unchecking the "Ignore stop events (&RTs)" ), and additionally decide whether to record only after the experiment finishes (check "Record RTs at end of script"). The latter option will not record all reaction times if you specify multiple repetitions of the same trial within the same pass through the script (since only one can be remembered for each line by the end of the experiment). If no stop event occurs, then a 0 secs time is recorded. Looking under the Resources section part allows you to continue sounds or PICTs until a stimulus of the same type replaces it. These are the Play sounds to next sound (‚åò-3) or Show PICTs for full times (‚åò-2) options. This allows you to run sounds (played asynchronously) into pictures. They can also be made to appear to start simultaneously. A negative value means MacStim should choose a random time at run time between 0.0 and the absolute value of max seconds.
5. The total trial duration ("tot"):
The total duration of the trial. This is equivalent to an inter-stimulus interval (or ISI), though it begins from the start of a trial (not the presentation of a stimulus). It is not entirely intuitive at first, so let me explain it in more detail. The minimum of tot will be pre + max seconds, and if you specify a time less than this sum, MacStim will actually default to the sum of pre + max suspecting you have made a mistake with tot. If you do specify tot as less than this sum (eg 0.00), then it means you do not wish MacStim to show the background resource again after the stimulus and before commencing the next trial. If you specify a longer interval than pre + max seconds then at the end of max secs, the background resource will be re-presented for a total of tot - (pre + max) seconds, ie the "remainder" secs. If you want to make the ISI constant then you should ensure that the sum for each trial of max + remainder + pre is the same (most simply by having the tot total times the same). Remember that any individual trial can be shown from 1 to a very large number of times (see "rep" below), and you can use a "dummy" blank trial at the start (or any time throughout your experiment) to separate dissimilar trials. A negative value means MacStim should choose a random time at run time between 0.0 and the absolute value of tot seconds.
6. The time to repeat the trial ("rep"):
The number of seconds to keep replaying this trial. If rep < tot or rep < (pre + max) then rep will not make any difference and is effectively set to zero seconds at run time. If rep is more than these sums, then the current trial will be repeated over until this time has elapsed. For example, you might want to show a PICT for a very small time period, such as flashing a checkerboard pattern, but repeat this process every 50 milliseconds for 10 secs, so you could specify pre as 0.050, max as 0.050, tot as 0.0, and rep as 10.0, with the alternating checkerboards as background and stimulus resources (see the Samples folder). The checkerboards would then alternate each 50 milliseconds for a total of 10 seconds, before MacStim would move onto the next trial. Any positive value can be used for rep (or 0.00).
One special case occurs when you have a block of trials ("b" or "r" trial type) as above. These use the rep field of the first of that block (the leader) to specify the maximum time to continue the whole block. If this time is larger than the sum of the individual trial durations, then the block will start over after once through. If smaller than the total block duration, then the block will finish after rep seconds, even if not all trials in that block have been completed. Note that if you leave this field as "0.0" seconds in the first trial of a block, then the block will not execute or funny flashing may occur as MacStim hurries to get through it! Pause trials ignore this field.
Note: if you check the "Absolute (not relative) block timing" checkbox in the Preferences Timing & Events pane, you can ensure that MacStim "catches" up any accrued deficits in timing due from block to block. In general, since timing is usually in microseconds there shouldn't be much need for this.
7. The event to end the stimulus resource ("stpEvt"):
This is the stop event to look for to end the stimulus prematurely (ie before max seconds expires). stpEvt is either a mouse click or key event specified by 'm' or 'k' respectively, a voice activated recording (through an attached or built in microphone) which is "v" or "V", a NuBus board triggered event ("t" or "T"), a serial event ('s' or 'S') which is any one character, or none ("n" or "N"). Other acceptable words are: 'mouse', 'mouse click', 'key press', 'key', key down', 'vox', 'voice', 'trigger', 'Trigger', 'serial', or 'Serial' which may improve legibility. If reaction times are to be recorded, this event triggers the end of the timing period since stimulus onset. For voice activation, you can elect to save the sound that triggered it (see Preferences topic).
8. The type of the background resource ("bg"):
This is the resource type for the background resource (or text type). PICTs, movies, sounds and no resources are currently acceptable. They are specified by "P", "p", "M", "m", "S", "s", "N", or "n" respectively, though you can also write them out in full, ie acceptable words include 'sound', 'Sound', 'Snd', 'snd', 'pic', 'picture', 'Pict', 'pict', 'movie', 'Movie', 'none', 'None', 'nothing', 'Nothing'. In addition, you can specify that the text written in the file name field(s) is to be used verbatim as text displayed on the screen, but using "t" or "T" in the bg field. Text will be displayed in the font, size, style and color as specified by the Stimulus Text button's settings (at the top of the script window) centered horizontally, and vertically (using the top line). Similar abbreviations are used for the st field.
9. The type of the stimulus resource ("st"):
This is the stimulus resource type. This will be started after a delay of pre seconds, and will continue up to max seconds, unless a cancel event or a specified stop event has been requested to terminate it.
10. The background file name ("bg-file"):
This is the name of the file to use as the background resource. Note that this must be exactly the same as the name of the file or it will not be found. If you indicate you wish no resource to be used during the background time then you should ensure that "bg" is set to "n" or "N" and the name in the "bg-file" field will be ignored (please ensure you have the correct number of tab characters between fields). If a "text" type resource is specified, then this is the verbatim text that should be displayed. Maximum length is 32 chars. This option can save an enormous amount of RAM (and time). You could also use customized fonts for such presentations.
11. The stimulus file name ("st-file"):
This is the exact file name of the file to load in for the stimulus in that trial. If you indicate you wish no stimulus resource to be used during the stimulus time ("n" or "N" in the "st" field) then you can again put any string you like after the last tab since it will be ignored.
12. The horizontal shift ("hShift"):
You can override the default setting of zero pixels horizontal shift by putting in a valid integer here in this field. The default center is test screen center, which can be poked horizontally and vertically in the Resources pane of the Preferences dialog for all displayed resources, but hShift integers allow further individual trial picture control. The limits are -10000 to 10000 pixels. Negative offsets move the picture to the left of the default center, positive ones to the right. These are particularly useful for animating the same or a small group of pictures. See the Bouncing Ball and Bouncing Text scripts for simple examples.
13. The vertical shift ("vShift"):
This is the same in the vertical direction as hShift, with negative integers raising the picture from the default center and positive lowering it.
Timing
Times for each trial's components are entered as decimal seconds. For most Macintoshes, the connection to the ADB port limits minimum response times to no less than 5 ms (since the Mac will not query the ADB port for activity any more often than this). This limitation does not affect the Mac Plus however, which will respond as soon as the stop event is encountered (it has no ADB port!), though this Mac (and the SE) do not have an Apple Sound Chip, so playing multiple sounds may be problematic (it is just not supported, but should not crash).
When the preloaded resources have been stored, the experiment's timing will commence as soon as the OK button is clicked (or the Return or Enter keys are pressed) to remove the dialog. This allows more than one machine to be synchronized to start at the same time. More accurate timing options are available if you use triggering signals from add-in boards (see the Add-On Cards topic), or perhaps the serial port will be adequate (see the "Serial Ports" topic). Serial port messages are placed in the code to occur at resource onset.
You can also specify absolute timing (using the "Absolute (not relative) block timing" checkbox in the Preferences Timing & Events pane), to ensure that MacStim "catches" up any accrued deficits in timing from block to block. In general, since timing is usually in microseconds there shouldn't be much need for this.
It is recommended that you test out your paradigm on the equipment to be used during your experiment before you need to use it in a real experiment! All times are in seconds with maximum specificable resolution of 1 ms, though the time taken to refresh the screen makes 17ms about the fastest you could achieve, but in practice most machines cannot show even small pictures with the usual drawing routines faster than each 2 ticks or so (40ms or so). You may therefore find that pictures "drop-out" and are not displayed if you specify times less than about 50 ms. Ensure you try your scripts before your experiments.
Note that movies sometimes take up to a few seconds to load into memory before they actually start playing. In general it is wise to assume that movies will have to be fully tested to see how long they take to execute rather than assuming that they will run exactly to time. In addition, be aware that running one movie after another may inevitably have a gap between the two movies (at least in this version). Although I have tried to reduce flashing between movies (when you have a non-white background color), this may occur just before the movie starts.
If you are using vox (voice activated stop events) to terminate the stimulus and record a reaction time, then be aware of some possible limitations. The quality of the sound recording (see the Preferences dialog Timing & Events pane) will determine how long you can record for a given number of kilobytes of disc space, ie best quality will take fewer seconds. You can set the number of Kbytes you wish each saved recording to be, and the volume of level of sound to initially activate recording. You can try these settings out in the Preferences dialog too with the Test button provided. When sounds are saved to disc, they may slow down timing if they are large or you have critical time requirements. Best to test rather than assuming your script will work. Sounds are saved in the Finder format with the 'snd ' resource in the resource fork. You can play them just by double clicking them (system 7) or in a program such as ResEdit. They are named with the script's session name (top right of the script window), followed by the seconds (since 1904) when they were recorded. This number matches that in the results Log window. To convert to an actual date & time, you could try DeskMates' conversion calculator (DeskMates is a shareware application also written by DD!) if you need to know exactly. Beware if you are trying to record sounds faster than 1 per second, that they might overwrite each other (ie same file name!).
